home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / standard / ldopen.z / ldopen
Encoding:
Text File  |  1998-10-30  |  7.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4. LLLLDDDDOOOOPPPPEEEENNNN((((3333XXXX))))                                                          LLLLDDDDOOOOPPPPEEEENNNN((((3333XXXX))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ldopen, ldaopen - open a common object file for reading
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssttttddddiiiioooo....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ffffiiiilllleeeehhhhddddrrrr....hhhh>>>>
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyymmmmssss....hhhh>>>>
  15.      ####iiiinnnncccclllluuuuddddeeee <<<<llllddddffffccccnnnn....hhhh>>>>
  16.  
  17.      LLLLDDDDFFFFIIIILLLLEEEE ****llllddddooooppppeeeennnn ((((filename, ldptr))))
  18.      cccchhhhaaaarrrr ****filename;;;;
  19.      LLLLDDDDFFFFIIIILLLLEEEE ****ldptr;;;;
  20.  
  21.      LLLLDDDDFFFFIIIILLLLEEEE ****llllddddaaaaooooppppeeeennnn ((((filename, oldptr))))
  22.      cccchhhhaaaarrrr ****filename;;;;
  23.      LLLLDDDDFFFFIIIILLLLEEEE ****oldptr;;;;
  24.  
  25.      iiiinnnntttt llllddddrrrreeeeaaaaddddsssstttt ((((ldptr, flags))))
  26.      LLLLDDDDFFFFIIIILLLLEEEE ****ldptr;
  27.      iiiinnnntttt flags;
  28.  
  29. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  30.      _l_d_o_p_e_n and _l_d_c_l_o_s_e(3X)  provide uniform access to simple object files and
  31.      to object files that are members of archive files.  An archive of common
  32.      object files can be processed as if it were a series of simple common
  33.      object files.
  34.  
  35.      If _l_d_p_t_r has the value NNNNUUUULLLLLLLL, _l_d_o_p_e_n opens _f_i_l_e_n_a_m_e, allocates and
  36.      initializes the LLLLDDDDFFFFIIIILLLLEEEE structure, and returns a pointer to the structure
  37.      to the calling program.
  38.  
  39.      If _l_d_p_t_r is valid and TTTTYYYYPPPPEEEE((((_l_d_p_t_r)))) is the archive magic number, _l_d_o_p_e_n
  40.      reinitializes the LLLLDDDDFFFFIIIILLLLEEEE structure for the next archive member of
  41.      _f_i_l_e_n_a_m_e.
  42.  
  43.      _l_d_o_p_e_n and _l_d_c_l_o_s_e work in concert.  _l_d_c_l_o_s_e returns FFFFAAAAIIIILLLLUUUURRRREEEE only when
  44.      TTTTYYYYPPPPEEEE((((_l_d_p_t_r)))) is the archive magic number and there is another file in the
  45.      archive to be processed.  Only then should _l_d_o_p_e_n be called with the
  46.      current value of _l_d_p_t_r.  In all other cases, and particularly when a new
  47.      _f_i_l_e_n_a_m_e is opened, _l_d_o_p_e_n should be called with a NNNNUUUULLLLLLLL _l_d_p_t_r argument.
  48.  
  49.      The following is a prototype for the use of _l_d_o_p_e_n and _l_d_c_l_o_s_e.  It
  50.      handles individual object (or a.out) files and (via the while-loop) an
  51.      archive file (see ar(1)) of object files.
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. LLLLDDDDOOOOPPPPEEEENNNN((((3333XXXX))))                                                          LLLLDDDDOOOOPPPPEEEENNNN((((3333XXXX))))
  71.  
  72.  
  73.  
  74.           /* for each filename to be processed */
  75.  
  76.           ldptr = NULL;
  77.           do  {
  78.                if ( (ldptr = ldopen(filename, ldptr)) != NULL )
  79.                {
  80.                     /* check magic number */
  81.                     /* process a single object file */
  82.                }
  83.           } while (ldclose(ldptr) == FAILURE );
  84.  
  85.      If the value of _o_l_d_p_t_r is not NNNNUUUULLLLLLLL, _l_d_a_o_p_e_n opens _f_i_l_e_n_a_m_e anew and
  86.      allocates and initializes a new LLLLDDDDFFFFIIIILLLLEEEE structure, copying the fields from
  87.      _o_l_d_p_t_r.  _l_d_a_o_p_e_n returns a pointer to the new LLLLDDDDFFFFIIIILLLLEEEE structure.  This new
  88.      pointer is independent of the old pointer, _o_l_d_p_t_r.  The two pointers can
  89.      be used concurrently to read separate parts of the object file.  For
  90.      example, one pointer can be used to step sequentially through the
  91.      relocation information while the other is used to read indexed symbol
  92.      table entries.
  93.  
  94.      _l_d_o_p_e_n and _l_d_a_o_p_e_n open _f_i_l_e_n_a_m_e for reading.  If _f_i_l_e_n_a_m_e cannot be
  95.      opened or if memory for the LLLLDDDDFFFFIIIILLLLEEEE structure cannot be allocated, both
  96.      functions return NNNNUUUULLLLLLLL.  A successful open does not ensure that the given
  97.      file is a common object file or an archived object file.  When calling
  98.      _l_d_o_p_e_n on a given a.out (rather than an archive) for the first time be
  99.      sure the second argument you pass is a NULL pointer ((LDFILE *)0) (this
  100.      is the only way to ensure the LDFILE * is initialized properly for that
  101.      a.out).
  102.  
  103.      _l_d_r_e_a_d_s_t reads in the portions of the symbol table implied by the _f_l_a_g_s
  104.      argument.  A _f_l_a_g_s argument of ----1111 reads in the entire symbol table.
  105.      Since the other routines, for example _l_d_t_b_r_e_a_d, ensure that the relevant
  106.      portions of the symbol table have been read in, you need not call
  107.      _l_d_r_e_a_d_s_t to use the other routines.  _l_d_r_e_a_d_s_t(_l_d_p_t_r,-_1) would simply
  108.      ensure the whole symbol table is read in at once, which is not necessary.
  109.      _l_d_r_e_a_d_s_t returns SSSSUUUUCCCCCCCCEEEESSSSSSSS if it has read in the symbol table successfully
  110.      or FFFFAAAAIIIILLLLUUUURRRREEEE if it cannot.  If an symbol table has been truncated or
  111.      damaged there is a small probability that _l_d_r_e_a_d_s_t will core dump rather
  112.      than return FFFFAAAAIIIILLLLUUUURRRREEEE ....
  113.  
  114.      _l_d_o_p_e_n causes the symbol table header and file descriptor table to be
  115.      read.  Further access, using _l_d_p_t_r, causes other appropriate sections of
  116.      the symbol table to be read (for example, if you call _l_d_t_b_r_e_a_d, _t_h_e
  117.      _s_y_m_b_o_l_s _o_r _e_x_t_e_r_n_a_l_s _a_r_e _r_e_a_d).  _T_o _f_o_r_c_e _s_e_c_t_i_o_n_s _o_f _t_h_e _s_y_m_b_o_l _t_a_b_l_e
  118.      _i_n_t_o _m_e_m_o_r_y, _c_a_l_l _l_d_r_e_a_d_s_t with _S_T__P* constants ORed together from
  119.      <_c_m_p_l_r_s/_s_t_s_u_p_p_o_r_t._h>.
  120.  
  121.      The program must be loaded with the object file access routine library
  122.      lllliiiibbbbmmmmlllldddd....aaaa.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. LLLLDDDDOOOOPPPPEEEENNNN((((3333XXXX))))                                                          LLLLDDDDOOOOPPPPEEEENNNN((((3333XXXX))))
  137.  
  138.  
  139.  
  140. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  141.      fopen(3S), ldclose(3X), ldfcn(4).
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.